﻿// <copyright file="IAuthorisationPolicyProvider.cs" company="SharpSTS">
// Copyright (c) 2007, 2008 All Right Reserved, http://sharpsts.com/
//
// This source is subject to the Microsoft Permissive License.
// Please see the License.txt file for more information.
// All other rights reserved.
//
// THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY 
// KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
// IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
// PARTICULAR PURPOSE.
//
// </copyright>
// <author>Barry Dorrans</author>
// <email>barryd@idunno.org</email>
// <date>2008-06-11</date>
// <summary>Defines the contract that a ClaimFiller provider must implement.</summary>

namespace SharpSTS
{
    using System.Collections.ObjectModel;
    using System.IdentityModel.Claims;
    using System.ServiceModel;

    /// <summary>
    /// Defines the contract that a ClaimFiller provider must implement to fill claims as part of the RSTR generation.
    /// </summary>
    [System.Diagnostics.CodeAnalysis.SuppressMessage(
        "Microsoft.Naming", 
        "CA1704:IdentifiersShouldBeSpelledCorrectly", 
        MessageId = "Authorisation",
        Justification = "We speak the Queen's English here.")]
    public interface IAuthorisationPolicyProvider
    {
        /// <summary>
        /// Provides the claim information for the listed claim and assigns the specified rights to those claims.
        /// </summary>
        /// <param name="userId">The user identifier to generation the card identifier for.</param>
        /// <param name="relyingParty">The <see cref="EndpointAddress"/> of the relying party that is requesting the claims.</param>
        /// <param name="claimTypes">A collection of claim types to provide information for.</param>
        /// <param name="rights">The rights to assign to this claim.</param>
        /// <returns>A readonly collection of filled claims.</returns>
        Collection<Claim> GetClaims(
            object userId, 
            EndpointAddress relyingParty,
            ReadOnlyCollection<string> claimTypes, 
            string rights);

        /// <summary>
        /// Returns a card identifier for the supplied username and card type.
        /// </summary>
        /// <param name="userId">The user identifier to generation the card identifier for.</param>
        /// <param name="authenticationType">The type of the authentication used for the card.</param>
        /// <returns>An identifier for an information card.</returns>
        string GetCardIdForUserId(object userId, AuthenticationType authenticationType);

        /// <summary>
        /// Returns a user identifier that the managed information card belongs to.
        /// </summary>
        /// <param name="cardId"> The card identifier.</param>
        /// <param name="authenticationType">The type of the authentication used for the card.</param>
        /// <returns>The user identifier the card belongs to.</returns>
        object GetUserIdFromCardId(string cardId, AuthenticationType authenticationType);

        /// <summary>
        /// Authenticates a username and password
        /// </summary>
        /// <param name="userName">The username to authenticate.</param>
        /// <param name="password">The password to authenticate.</param>
        /// <returns>True if athenticated, otherwise false.</returns>
        bool AuthenticateUserNamePassword(string userName, string password);

        /// <summary>
        /// Validates the association between the authenticated user for a username/password backed card
        /// and the card id used during the request.
        /// </summary>
        /// <param name="userName">User name sent during authentication.</param>
        /// <param name="cardId">Card identity of the card used to send the request.</param>
        /// <param name="cardVersion">The version number of the card presented.</param>
        /// <returns>True if the username is authorised to use the card, otherwise false.</returns>
        [System.Diagnostics.CodeAnalysis.SuppressMessage(
            "Microsoft.Naming", 
            "CA1704:IdentifiersShouldBeSpelledCorrectly", 
            MessageId = "Authorised",
            Justification = "We speak the Queen's English here")]
        bool AuthorisedToUseCardId(string userName, string cardId, int cardVersion);

        /// <summary>
        /// Validates the association between the PPID for a self-issued backed card
        /// and the card id used during the request.
        /// </summary>
        /// <param name="privatePersonalIdentifier">PPID sent during authentication.</param>
        /// <param name="issuerPublicKeyHash">A hash of the public key of the issuer for the PPID claim.</param>
        /// <param name="cardId">Card identity of the card used to send the request.</param>
        /// <param name="cardVersion">The version number of the card presented.</param>
        /// <returns>True if the username is authorised to use the card, otherwise false.</returns>
        bool AuthorisedToUseCardId(Claim privatePersonalIdentifier, string issuerPublicKeyHash, string cardId, int cardVersion);

        /// <summary>
        /// Decides if the information card used requires a refresh.
        /// </summary>
        /// <param name="cardId">The card identifier.</param>
        /// <param name="cardVersion">The card version.</param>
        /// <returns>True if a card refresh is required, otherwise false.</returns>
        bool IsCardRefreshRequired(string cardId, int cardVersion);

        /// <summary>
        /// Gets the PPID.
        /// </summary>
        /// <param name="cardId">The card identifier for the current request</param>
        /// <param name="endpoint">The relying party <see cref="EndpointAddress"/>.</param>
        /// <param name="selectorSuggestedPPID">The selector suggested PPID.</param>
        /// <returns>A PPID for the card identifier and relying party.</returns>
        /// <remarks>Implementation of this method is optional; PPID generation may be provided by a seperate <see cref="PPIDGeneratorProvider"/></remarks>
        string GetPPID(string cardId, EndpointAddress endpoint, string selectorSuggestedPPID);

        /// <summary>
        /// Returns the display description for a given claim URI.
        /// </summary>
        /// <param name="claimType">The claim to provide the display name for.</param>
        /// <returns>
        /// The display description for the specified claim.
        /// </returns>        
        /// <remarks>Display names for standard <see cref="ClaimTypes"/> are automatically provided. Custom claim display descriptions
        /// are set by the Description element in the SupportedClaims configuration collection.</remarks>
        string GetDisplayName(string claimType);
    }
}
